home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 3 / Amiga Tools 3.iso / audio / playmod / ptreplay.doc < prev    next >
Text File  |  1995-04-23  |  15KB  |  556 lines
  1. TABLE OF CONTENTS
  2.  
  3. ptreplay.library/PTFade
  4. ptreplay.library/PTFreeMod
  5. ptreplay.library/PTGetPri
  6. ptreplay.library/PTInstallBits
  7. ptreplay.library/PTLoadModule
  8. ptreplay.library/PTOffChannel
  9. ptreplay.library/PTOnChannel
  10. ptreplay.library/PTPatternData
  11. ptreplay.library/PTPatternPos
  12. ptreplay.library/PTPause
  13. ptreplay.library/PTPlay
  14. ptreplay.library/PTResume
  15. ptreplay.library/PTSetPos
  16. ptreplay.library/PTSetPri
  17. ptreplay.library/PTSetupMod
  18. ptreplay.library/PTSetVolume
  19. ptreplay.library/PTSongLen
  20. ptreplay.library/PTSongPattern
  21. ptreplay.library/PTSongPos
  22. ptreplay.library/PTStartFade
  23. ptreplay.library/PTStop
  24. ptreplay.library/PTUnloadModule
  25. ptreplay.library/PTFade                               ptreplay.library/PTFade
  26.  
  27.    NAME
  28.         PTFade -- Let a module "slide away" before it's stopped (V2)
  29.  
  30.    SYNOPSIS
  31.         PTFade(module,speed)
  32.                 A0     D0
  33.         void PTFade(struct Module *, UBYTE);
  34.  
  35.    FUNCTION
  36.         This function does smooth vol slidedown until volume reaches zero,
  37.         then the module is stoped and the function returns. The speed is
  38.         given in the number of "vblanks" (ie CIA timeouts because it uses
  39.         CIA timing instead of vblank timing) between each step.
  40.  
  41.    INPUTS
  42.         module - module that is to be stoped.
  43.         speed - fading speed.
  44.  
  45.    SEE ALSO
  46.         PTStartFade()
  47.  
  48. ptreplay.library/PTFreeMod                         ptreplay.library/PTFreeMod
  49.  
  50.    NAME
  51.         PTFreeMod -- Deallocates a module create with PTSetupMod. (V4)
  52.  
  53.    SYNOPSIS
  54.         PTFreeMod(Module)
  55.                   A0
  56.         void PTFreeMod(struct Module *);
  57.  
  58.    FUNCTION
  59.         This function will free all memory allocated by the PTSetupMod
  60.         function.
  61.  
  62.    INPUTS
  63.         Module - a module returned by PTSetupMod().
  64.  
  65.    SEE ALSO
  66.         PTSetupMod()
  67.  
  68. ptreplay.library/PTGetPri                           ptreplay.library/PTGetPri
  69.  
  70.    NAME   
  71.         PTGetPri -- Return the priority currently used. (V5)
  72.  
  73.    SYNOPSIS
  74.         Pri=PTSetPri()
  75.         D0
  76.         BYTE PTSetPri(void);
  77.  
  78.    FUNCTION
  79.         This function returnes the current priority on wich ptreplay hold
  80.         it's channels.
  81.  
  82.    RESULT
  83.         Pri - The priority currently used by ptreplay.
  84.  
  85.    SEE ALSO
  86.         PTSetPri()
  87.  
  88. ptreplay.library/PTInstallBits                 ptreplay.library/PTInstallBits
  89.  
  90.    NAME
  91.         PTInstallBits -- Defines what to be signaled at and how (V4)
  92.  
  93.    SYNOPSIS
  94.         PTInstallBits(Module, Restart, Pos, Row, Fade);
  95.                       A0      D0       D1   D2   D3
  96.         void PTInstallBits(struct Module *, BYTE, BYTE, BYTE, BYTE);
  97.  
  98.    FUNCTION
  99.         This function is used to inform ptreplay which signals to send to
  100.         this task at the given positions. Currently it can only be set up to
  101.         signal one task/module (the one calling this function) this may
  102.         however change in future. A signalbit of -1 tells ptreplay not to
  103.         signal you at that specific location.
  104.  
  105.    INPUTS
  106.         Module - module to use the given signals
  107.         Restart - Bit to set when a module restarts from beginning or -1 for
  108.             no signal.
  109.         Pos - Bit to set when moving to next position or -1 for no signal
  110.         Row - Bit to set when moving to next row in pattern or -1 for no
  111.             signal.
  112.         Fade - Bit to set when PTStartFade is done and have stoped module or
  113.             -1 for no signal.
  114.  
  115.    EXAMPLE
  116.         /* This will set signalbit 4 when the module restarts */
  117.         PTInstallBits(Module, 4, -1, -1, -1);
  118.  
  119.         /* This will set signalbit 0 when startfade has stopped the module */
  120.         PTInstallBits(Module, -1, 1, -1, 0);
  121.  
  122.    SEE ALSO
  123.         PTStartFade()
  124.  
  125. ptreplay.library/PTLoadModule                   ptreplay.library/PTLoadModule
  126.  
  127.    NAME
  128.         PTLoadModule -- Load a module.
  129.  
  130.    SYNOPSIS
  131.         module=PTLoadModule(name)
  132.           D0                A0
  133.         struct module *PTLoadModule(STRPTR);
  134.  
  135.    FUNCTION
  136.         The named file is loaded into chip-mem and if it's identified as an
  137.         protracker module, a module control structure is created and then
  138.         returned to you for usage in the other functions like PTPlay
  139.  
  140.    INPUTS
  141.         name - name of a module file.
  142.  
  143.    RESULT
  144.         module - a pointer to a module control structure or NULL if the
  145.             module couldn't be loaded.
  146.  
  147.    SEE ALSO
  148.         PTSetupMod(), PTUnloadModule()
  149.  
  150. ptreplay.library/PTOffChannel                   ptreplay.library/PTOffChannel
  151.  
  152.    NAME   
  153.         PTOffChannel -- Turns off one or more channels. (V5)
  154.  
  155.    SYNOPSIS
  156.         PTStartFade(Module, Channel)
  157.                     A0      D0
  158.         void PTStartFade(struct Module *, BYTE);
  159.  
  160.    FUNCTION
  161.         This function is used to turn one or more channels off in order to
  162.         stop ptreplay producing sound for that channel. Note that this isn't
  163.         a nested command and turning off a channel that is already off will
  164.         give you strange results and is _not_ recomended.
  165.  
  166.    INPUTS
  167.         Module - Module to select channels for.
  168.         Channel - Channels to be turned off.
  169.  
  170.    RESULT
  171.  
  172.    EXAMPLE
  173.  
  174.    NOTES
  175.  
  176.    BUGS
  177.         Turning a channel off will not release it to be used by other
  178.         programms
  179.  
  180.    SEE ALSO
  181.         PTOnChannel()
  182.  
  183. ptreplay.library/PTOnChannel                     ptreplay.library/PTOnChannel
  184.  
  185.    NAME   
  186.         PTOnChannel -- Turns on one or more channels. (V5)
  187.  
  188.    SYNOPSIS
  189.         PTStartFade(Module, Channel)
  190.                     A0      D0
  191.         void PTStartFade(struct Module *, BYTE);
  192.  
  193.    FUNCTION
  194.         This function is used to turn one or more channels on in order for
  195.         ptreplay to produce sound for that channel. Note that this isn't
  196.         a nested command and turning on a channel that is already on will
  197.         give you strange results.
  198.  
  199.    INPUTS
  200.         Module - Module to select channels for.
  201.         Channel - Channels to be turned on.
  202.  
  203.    SEE ALSO
  204.         PTOffChannel()
  205.  
  206. ptreplay.library/PTPatternData                 ptreplay.library/PTPatternData
  207.  
  208.    NAME
  209.         PTPatternData -- Returns the adress of specified pattern/row (V4)
  210.  
  211.    SYNOPSIS
  212.         RowData=PTPatternData(Module, PatternNum, RowNum)
  213.         D0                    A0      D0          D1
  214.         APTR PTPatternData(struct Module *, UBYTE, UBYTE);
  215.  
  216.    FUNCTION
  217.         This function returns a pointer to the given row in the specified
  218.         pattern.
  219.  
  220.    INPUTS
  221.         Module - Pointer to the module you which to examine.
  222.         PatternNum - The pattern (0-127) you want to examine.
  223.         RowNum - And finaly which row (0-63) to examine.
  224.  
  225.    RESULT
  226.         RowData - A pointer to the given position
  227.  
  228. ptreplay.library/PTPatternPos                   ptreplay.library/PTPatternPos
  229.  
  230.    NAME
  231.         PTPatternPos -- Returns the patternrow currently playing (V4)
  232.  
  233.    SYNOPSIS
  234.         Row=PTPatternPos(module)
  235.         D0               A0
  236.         UBYTE PTPatternPos(struct Module *);
  237.  
  238.    FUNCTION
  239.         Returns the row in the pattern that it is currently being played.
  240.  
  241.    INPUTS
  242.         module - A module that is currently being played.
  243.  
  244.    RESULT
  245.         Row - The row (0-63 $00-$40) that is being played.
  246.  
  247. ptreplay.library/PTPause                             ptreplay.library/PTPause
  248.  
  249.    NAME
  250.         PTPause -- pauses a module.
  251.  
  252.    SYNOPSIS
  253.         PTPause(module)
  254.                 A0
  255.         void PTPause(struct Module *);
  256.  
  257.    FUNCTION
  258.         Pause this module, remembering the position so that you can restart
  259.         it later. All sound is turned off.
  260.  
  261.    INPUTS
  262.         module - pointer to module control structure.
  263.  
  264.    BUGS
  265.         All channels are still allocated att the same priority after this
  266.         functions has returned so it's vise to lower the priority to -128
  267.         before calling this function.
  268.  
  269.    SEE ALSO
  270.         PTResume()
  271.  
  272. ptreplay.library/PTPlay                               ptreplay.library/PTPlay
  273.  
  274.    NAME
  275.         PTPlay -- Plays a module
  276.  
  277.    SYNOPSIS
  278.         PTPlay(module)
  279.                 A0
  280.         void PTPlay(struct Module *);
  281.  
  282.    FUNCTION
  283.         Start playing the module from the beginning. If this module already
  284.         was playing, it starts over from the beginning.
  285.  
  286.    INPUTS
  287.         module - pointer to module control structure.
  288.  
  289.    BUGS
  290.         It is not yet supported to call this function while another module
  291.         is playing.
  292.         If another module is playing, it will be stopped and this will be
  293.         played instead (V5)
  294.  
  295.    SEE ALSO
  296.         PTStop()
  297.  
  298. ptreplay.library/PTResume                           ptreplay.library/PTResume
  299.  
  300.    NAME
  301.         PTResume -- restarts a paused module.
  302.  
  303.    SYNOPSIS
  304.         PTResume(module)
  305.                  A0
  306.         void PTResume(struct Module *);
  307.  
  308.    FUNCTION
  309.         Resume playing this module, after it was paused. If it was not
  310.         paused then nothing happens. Becasue PTPause&PTResume doesn't nest
  311.         so will the module continue after the first call to PTResume.
  312.  
  313.    INPUTS
  314.         module - pointer to module control structure.
  315.  
  316.    SEE ALSO
  317.         PTPause()
  318.  
  319. ptreplay.library/PTSetPos                           ptreplay.library/PTSetPos
  320.  
  321.    NAME   
  322.         PTSetPos -- Changes the position for a playing module. (V5)
  323.  
  324.    SYNOPSIS
  325.         PTSetPos(Module, Pos)
  326.                  A0      D0
  327.         void PTSetPos(struct Module *, UBYTE);
  328.  
  329.    FUNCTION
  330.         This function changes the position which we are playing to the new
  331.         one. 
  332.  
  333.    INPUTS
  334.         Module - Module to change pos in.
  335.         Pos - The new position 0 - SongLen-1
  336.  
  337.    SEE ALSO
  338.         PTSongPos(), PTSongLen()
  339.  
  340. ptreplay.library/PTSetPri                           ptreplay.library/PTSetPri
  341.  
  342.    NAME
  343.         PTSetPri -- Sets the priority that ptreplay should use. (V5)
  344.  
  345.    SYNOPSIS
  346.         PTSetPri(Pri)
  347.                  D0
  348.         void PTSetPri(BYTE);
  349.  
  350.    FUNCTION
  351.         This function changes the priority on wich ptreplay hold it's
  352.         channels. It deafults to -128 and is also reset to -128 every time
  353.         the library is closed (OpenCnt==NULL).
  354.  
  355.    INPUTS
  356.         Pri - The new priority
  357.  
  358.    SEE ALSO
  359.         PTGetPri()
  360.  
  361. ptreplay.library/PTSetupMod                       ptreplay.library/PTSetupMod
  362.  
  363.    NAME
  364.         PTSetupMod -- Creates a control structure for a loaded module. (V4)
  365.  
  366.    SYNOPSIS
  367.         Module = PTSetupMod(LoadedMod);
  368.         D0                  A0
  369.         struct Module *PTSetupMod(APTR);
  370.  
  371.    FUNCTION
  372.         This function will allocate a module control structure and intilize
  373.         it using an already loaded module file, in order to use in with
  374.         ptreplay.
  375.  
  376.    INPUTS
  377.         LoadedMod - An pointer to an already loaded module.
  378.  
  379.    RESULT
  380.         Module - A module control structure ready to use.
  381.  
  382.    EXAMPLE
  383.         /* This routine will do the same thing as PTLoadMod */
  384.         BPTR File;
  385.         APTR Mod;
  386.         int Len;
  387.         struct Module *Module;
  388.  
  389.         File=Open("mod.module",MODE_OLDFILE))
  390.         Seek(File, 0l, OFFSET_END);
  391.         Len=Seek(File, 0l, OFFSET_BEGINNING);
  392.  
  393.         Mod=AllocMem(Len, MEMF_CHIP);
  394.         Read(File, Mod, Len);
  395.         Close(File);
  396.         Module=PTSetupMod(Mod);
  397.  
  398.    NOTES
  399.         1. The module MUST already be located in chip mem.
  400.         2. The module MUST be valid while the module is goint to be used.
  401.         Both may change in future.
  402.  
  403.    SEE ALSO
  404.         PTFreeMod()
  405.  
  406. ptreplay.library/PTSetVolume                     ptreplay.library/PTSetVolume
  407.  
  408.    NAME   
  409.         PTSetVolume -- Sets the base volume (V3)
  410.  
  411.    SYNOPSIS
  412.         PTSetVolume(module,volume)
  413.                     A0     D0
  414.         void PTSetVolume(struct Module, UBYTE);
  415.  
  416.    FUNCTION
  417.         This function will change the base volume that ptreplay uses to
  418.         calculate the "real" volume for the specified module. 
  419.  
  420.    INPUTS
  421.         module - pointer to module.
  422.         speed - new volume  0-64 ($00-$40)
  423.  
  424. ptreplay.library/PTSongLen                         ptreplay.library/PTSongLen
  425.  
  426.    NAME
  427.         PTSongLen -- returns songlength (V4)
  428.  
  429.    SYNOPSIS
  430.         Len=PTSongLen(module)
  431.         d0            a0
  432.         UBYTE PTSongLen(struct Module *);
  433.  
  434.    FUNCTION
  435.         *This funktion returns the length of the module is positions. This
  436.         is the same value as Length in ProTracker and means that it will
  437.         play until position Len-1.
  438.  
  439.    INPUTS
  440.         module - The module whos length you which to now.
  441.  
  442.    RESULT
  443.         Len - Number of positions in module
  444.  
  445. ptreplay.library/PTSongPattern                 ptreplay.library/PTSongPattern
  446.  
  447.    NAME   
  448.         PTSongPattern -- Returns pattern at a given position (V4)
  449.  
  450.    SYNOPSIS
  451.         PatNum=PTSongPattern(module, pos)
  452.         D0                   A0      D0
  453.         UBYTE PTSongPattern(struct Module *,UWORD);
  454.  
  455.    FUNCTION
  456.         Returns the pattern number at a given position.
  457.  
  458.    INPUTS
  459.         Module - The module you want to examine
  460.         Pos - The position (0-127) you want to examine.
  461.  
  462.    RESULT
  463.         PatNum - A number (0-127) telling you which pattern is to be played.
  464.  
  465. ptreplay.library/PTSongPos                         ptreplay.library/PTSongPos
  466.  
  467.    NAME
  468.         PTSongPos -- Gives you the current song position (V4)
  469.  
  470.    SYNOPSIS
  471.         Pos=PTSongPos(module);
  472.         d0            A0
  473.         UBYTE PTSongPos(struct Module *)
  474.  
  475.    FUNCTION
  476.         This function returns the position the module is curently playing.
  477.  
  478.    INPUTS
  479.         module - pointer to a module that is playing.
  480.  
  481.    RESULT
  482.         Pos - position 0 - (Length-1)
  483.  
  484.    SEE ALSO
  485.         PTSetPos()
  486.  
  487. ptreplay.library/PTStartFade                     ptreplay.library/PTStartFade
  488.  
  489.    NAME
  490.         PTStartFade -- Let a module fade-away before it's stopped (V4)
  491.  
  492.    SYNOPSIS
  493.         PTStartFade(Module, Speed)
  494.                     A0      D0
  495.         void PTStartFade(struct Module *, UBYTE);
  496.  
  497.    FUNCTION
  498.         This function will also do a smooth volume slidedown in the same way
  499.         as PTFade does but it returns as soon as the fading has started
  500.         instead of when it is done. Currently the only way to notice when
  501.         the module is stoped is to setup a Fade bit using PTInstallBits and
  502.         check for that bit.
  503.  
  504.    INPUTS
  505.         Module - Module to be stoped.
  506.         Speed - fading speed.
  507.  
  508.    SEE ALSO
  509.         PTFade(), PTInstallBits()
  510.  
  511. ptreplay.library/PTStop                               ptreplay.library/PTStop
  512.  
  513.    NAME
  514.         PTStop -- Stops a module that is playing.
  515.  
  516.    SYNOPSIS
  517.         PTStop(module)
  518.                 A0
  519.         void PTStop(struct Module *);
  520.  
  521.    FUNCTION
  522.         Stop playing the given module. If it wasn't playing, nothing
  523.         happens.
  524.  
  525.    INPUTS
  526.         module - pointer to module control structure.
  527.  
  528.    SEE ALSO
  529.         PTPlay(), PTFade()
  530.  
  531. ptreplay.library/PTUnloadModule               ptreplay.library/PTUnloadModule
  532.  
  533.    NAME
  534.         PTUnloadModule -- Deallocates a loaded module.
  535.  
  536.    SYNOPSIS
  537.         PTUnloadModule(module)
  538.                         A0
  539.         void PTUnloadModule(struct Module *);
  540.  
  541.    FUNCTION
  542.         Deallocates a previsly loaded module, returning all it's resources
  543.         to the system.
  544.  
  545.    INPUTS
  546.         module - pointer to module control structure returned by LoadModule.
  547.  
  548.    BUGS
  549.         Does not check that module is stopped. If you call this function on
  550.         a module that is playing, you _will_ cause a System Failure. You
  551.         have been warned.
  552.  
  553.    SEE ALSO
  554.         PTFreeMod(), PTStop()
  555.  
  556.